Changes between Initial Version and Version 1 of Openfire Client SSL Authentication How-to

Timestamp:

Nov 29, 2011, 3:06:28 AM (12 years ago)

Author:

ljfisher

Comment:

--

Openfire Client SSL Authentication How-to

@@ +1 @@
+Openfire is the only open source XMPP server (that I know of) that supports
+client-side certificate authentication. This will explain how to setup
+Openfire and Pidgin to using client-side certificate authentication.
+
+
+= Create Certificates = 
+
+1. You will need to create a test certificate authority. A number of web sites have how-tos on creating a certificate authority for testing. 
+
+ * Using a nice GUI interface:
+     http://www.gria.org/documentation/5.3/how-tos/certificate-authority-signing-information
+
+ * Using the OpenSSL CA tools:
+      http://www.debian-administration.org/articles/618
+
+   Create a certificate/key pair for each user. 
+
+   ** The certificate's COMMON NAME must match the XMPP login name **
+
+
+2. Create a PKCS12 file containing the certificate/key pair. The files need to be in PEM (text) format for openssl and not DER (binary).
+
+ * To convert a certificate to PEM format:
+      openssl x509 -inform der -in DER_CERT_FILE -outform pem PEM_CERT_FILE
+
+ * To convert a key to PEM format:
+      openssl pkey -inform der -in DER_KEY_FILE -outform pem PEM_KEY_FILE
+
+ * To create the PKCS12 file:
+      openssl pkcs12 -export -inkey KEYFILE -in CERTFILE -out USER.p12 -name USER
+
+
+= Setting Up Openfire = 
+
+1. Download, install, and setup Openfire:
+    http://www.igniterealtime.org/projects/openfire/index.jsp
+    http://www.igniterealtime.org/builds/openfire/docs/latest/documentation/install-guide.html
+
+2. Openfire maintains several key stores in /etc/openfire/security. We are interested in client.truststore which contains the certificates trusted to authenticate users. We can place a certificate authority certificate in the key store and any certificates signed by the authority will be accepted for login to the server.
+
+   To add a certificate:
+     keytool -importcert -keystore /etc/openfire/security/client.truststore -alias NAME -file CERTFILE
+
+   The default password is "changeit"
+
+   Be sure to say yes to "Trust this certificate?".
+
+3. Login to you Openfire server on http://server:9090 and go to Server->Server Manager->System Properties. Ensure the following properties exist and are set:
+
+||= Property                                =||= Value =||
+|| xmpp.client.cert.policy                   || "needed" or "wanted" ||
+|| xmpp.client.certificate.accept-selfsigned || true ||
+|| xmpp.client.certificate.verify            || true ||
+|| xmpp.client.certificate.verify.chain      || true ||
+|| xmpp.client.certificate.verify.root       || true ||
+|| sasl.mechs                                || EXTERNAL (plus whatever else) ||
+
+   More properties can be found here:
+    http://community.igniterealtime.org/thread/45670
+    http://community.igniterealtime.org/thread/37967
+
+4. Add a user with the same username as the common name of the certificate you created above in Users/Groups->Users->Create New User.
+
+= Build Pidgin with Client Certificate Authentication =
+
+1. Pull the im.pidgin.cpw.ljfisher.ssl_client_auth branch from the pidgin monotone repository.
+
+2. Ensure the following prerequisites are installed:
+    * gnutls 2.10 +  Older versions will work but exporting certificates and keys will fail
+    * Cyrus SASL
+
+3. Configure Pidgin with these options:
+     ./configure --enable-cyrus-sasl --enable-gnutls=yes
+
+4. Build and install Pidgin:
+     make install
+
+= Configure Pidgin =
+
+1. Open Tools -> Certificates -> Your Certificatesw. Select Add. Select the PKCS12 file, USER.p12, created above. Enter a passwords and name.
+
+2. Create a XMPP (Jabber) account.
+
+   On the Basic tab:
+      a. Enter a username same as the commone name in the certificate
+
+   On the Advanced tab:
+      a. Select Connection Security: Use old-sylte SSL
+      b. Select Login certificate: the cert you added above
+      c. Change connection port to 5223.
+
+   Openfire doesn't seem to play well with client authentication using starttls so we use regular SSL which uses port 5223.
+
+3. Enable the account and it should login.
+
+
+= Troubleshooting =
+
+== You get SSL Handshake failed messages ==
+
+a. Check that /etc/openfire/security/client.truststore is readable by openfire user.
+b. Check that the certificate authority's certificate has been added to  /etc/openfire/security/client.truststore and has been trusted:
+      keytool -list -keystore /etc/openfire/security/client.truststore
+c. Check that the user name matches the common name of the login certificate.
+
+== You get a password dialog when trying to login even though you selected a login certificate ==
+
+a. Check that EXTERNAL has been added to the sasl.mechs Openfire server property.
+b. Check that the user name matches the common name of the login certificate.
+c. Check that there is an account for the user on the Openfire server
+
+
+== Bug Reports ==
+
+If you cannot resolve the issue send a capture of the Pidgin debug output by running Pidgin with debug and GNUTLS debug enabled:
+   PURPLE_GNUTLS_DEBUG=9 pidgin -d > pidgin.dbg
+
+And capture the login using Wireshark and send a pcap.